/// 跨平台目录选择结果的统一封装。
///
/// - 在 **桌面 / 移动端**：
///   - [displayPath] 为真实的本地目录路径，例如 `/Users/alice/projects/demo`。
///   - [webHandle] 始终为 `null`。
///
/// - 在 **Web 平台**：
///   - 由于浏览器安全限制，没有真实文件系统路径；
///   - [displayPath] 仅用于展示，例如 `fs://Documents`；
///   - [webHandle] 为原生的 `FileSystemDirectoryHandle`，可用于后续文件操作。
class PickedDirectory {
  /// 用于显示或持久化的“路径”字符串。
  ///
  /// - 在非 Web 平台：保存真实目录路径；
  /// - 在 Web 平台：保存 `fs://{dirName}` 格式的虚拟路径。
  final String displayPath;

  /// Web 平台特有：浏览器返回的 `FileSystemDirectoryHandle`。
  ///
  /// - 桌面 / 移动端始终为 `null`；
  /// - 在 Web 上用于后续文件系统 API 调用。
  final Object? webHandle;

  /// 创建一个 [PickedDirectory]。
  ///
  /// - [displayPath] 始终必填；
  /// - [webHandle] 仅在 Web 平台下传入。
  PickedDirectory({
    required this.displayPath,
    this.webHandle,
  });
}
